Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Base Media Handler Utility Function

Apple's base media handler component provides a utility function, MediaSetHandlerCapabilities , which allows you to tell the base handler what your derived handler can do.

MediaSetHandlerCapabilities

The MediaSetHandlerCapabilities function allows your derived media handler to report its capabilities to the base media handler.

pascal ComponentResult MediaSetHandlerCapabilities
                                         (MediaHandler mh,
                                          long flags,
                                          long flagsMask);
mh
Identifies your derived media handler's connection to the base media handler.
flags
Specifies the capabilities of your derived media handler. This parameter contains a number of flags, each of which corresponds to a particular feature. You may work with more than one flag at a time. The following flags are defined (be sure to set unused flags to 0):
handlerHasSpatial
Indicates that your handler does spatial processing. If you set this flag to 1, the Movie Toolbox informs your derived media handler about changes to the graphics environment or spatial representation of your media.
handlerCanClip
Indicates that your media handler can perform clipping. If you set this flag to 1, the Movie Toolbox calls your MediaSetClip function (described on MediaSetClip ) whenever the clipping region changes.
handlerCanMatte
Reserved for Apple. Do not set this flag to 1.
handlerCanTransferMode
Indicates that you can work with transfer modes other than source copy or dither copy. If you set this flag to 1, the Movie Toolbox calls your MediaGetTrackOpaque function to determine whether your track is transparent.
handlerNeedsBuffer
Indicates that your media handler needs help during playback. If you set this flag to 1, the base media handler allocates an offscreen buffer and handles all display transformations for you.
handlerNoIdle
Indicates that your derived media handler does not need any processing time during playback. If you set this flag to 1, the Movie Toolbox never calls your MediaIdle function. This is useful for media handlers that store data in a media, but do not play that data.
handlerNoScheduler
Indicates that your media handler performs special processing during playback. Normally, the Movie Toolbox calls your MediaIdle function only when it is time for your handler to draw data from a new media sample. If you set this flag to 1, the Movie Toolbox calls that function other times as well, so that your media handler can prepare for playback or perform other necessary processing.
handlerWantsTime
Indicates that your media handler needs additional processing time. If you set this flag to 1, the Movie Toolbox calls your MediaIdle function as often as possible.
handlerCGrafPortOnly
Indicates that your media handler can only draw into color graphics ports. If you set this flag to 1, the base media handler performs the necessary processing to display your color media on a black-and-white graphics port (this involves drawing to an offscreen buffer and then transferring the image to the screen).
flagsMask
Indicates which flags in the flags parameter are to be considered in this operation. For each bit in the flags parameter that you want the base media handler to consider, you must set the corresponding bit in the flagsMask parameter to 1. Set unused flags to 0. This allows you to work with a single flag without altering the settings of other flags.

DESCRIPTION

Use the MediaSetHandlerCapabilities function to tell the base media handler what your derived media handler can do. By default, all of the flags are set to 0--in this case, your media handler is only responsible for storing and retrieving data. You can specify further capabilities by setting various flags to 1. For example, if your handler draws data on the screen, be sure to set the handlerHasSpatial flag to 1. Other flags govern more detailed aspects of handler operation.

This function uses both a flags parameter and a flagsMask parameter. You specify which flags are to be changed in a given operation by setting the flagsMask parameter. You then specify the new values for those affected flags with the flags parameter. In this manner, you can work with a single flag without affecting the settings of any other flags.

Your media handler may call this function at any time. In general, you should call it from your MediaInitialize function (described on MediaInitialize ), so that you report your capabilities to the base media handler before the Movie Toolbox starts working with your media. You may call this function again later, in response to changing conditions. For example, if your media handler receives a matrix that it cannot accommodate from the MediaSetMatrix function, you can allow the base media handler to handle your drawing by calling this function and setting the handlerNeedsBuffer flag in both the flags and flagsMask parameters to 1.

Note that this function is provided by the base media handler--your media handler does not support this function.

RESULT CODES

Any Component Manager result code

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next